home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume32 / perlref / part02 < prev    next >
Encoding:
Text File  |  1992-09-04  |  54.1 KB  |  1,831 lines

  1. Newsgroups: comp.sources.misc,comp.lang.perl
  2. From: jv@mh.nl (Johan Vromans)
  3. Subject:  v32i002:  perlref - Perl Reference Guide 4.035.1, Part02/04
  4. Message-ID: <1992Sep4.023901.11943@sparky.imd.sterling.com>
  5. X-Md4-Signature: 3d807c649ea5e54444c2b2a792f93f8c
  6. Date: Fri, 4 Sep 1992 02:39:01 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: jv@mh.nl (Johan Vromans)
  10. Posting-number: Volume 32, Issue 2
  11. Archive-name: perlref/part02
  12. Supersedes: perlref: Volume 28, Issue 77-79
  13. Environment: Perl v4.035
  14.  
  15. #! /bin/sh
  16. # This is a shell archive.  Remove anything before this line, then feed it
  17. # into a shell via "sh file" or similar.  To overwrite existing files,
  18. # type "sh file -c".
  19. # Contents:  Makefile refbase.tex
  20. # Wrapped by kent@sparky on Wed Sep  2 21:35:21 1992
  21. PATH=/bin:/usr/bin:/usr/ucb:/usr/local/bin:/usr/lbin ; export PATH
  22. echo If this archive is complete, you will see the following message:
  23. echo '          "shar: End of archive 2 (of 4)."'
  24. if test -f 'Makefile' -a "${1}" != "-c" ; then 
  25.   echo shar: Will not clobber existing file \"'Makefile'\"
  26. else
  27.   echo shar: Extracting \"'Makefile'\" \(3058 characters\)
  28.   sed "s/^X//" >'Makefile' <<'END_OF_FILE'
  29. X# @(#)@ Makefile 4.2.7 - Makefile for Perl Reference Guide
  30. X
  31. X# This Makefile requires perl to be in your PATH.
  32. X
  33. XSHELL    = /bin/sh
  34. XLATEX    = latex
  35. XDVIPS    = dvips
  36. X
  37. X# Delete the next line if you use US Letter paper format
  38. XPAPER    = -a4
  39. X
  40. Xall:    refguide.ps
  41. X
  42. X2pass:    guide-odd.ps guide-even1.ps guide-even2.ps
  43. X
  44. X# 2 pages per page, suitable for centrefold printing.
  45. Xrefguide.ps:    refbase.ps parr
  46. X    perl ./parr $(PAPER) \
  47. X        -o 21,2,3,20,19,4,5,18,17,6,7,16,15,8,9,14,13,10,11,12 \
  48. X        refbase.ps > refguide.ps
  49. X
  50. X# Odd and even passes for centerfold printing. 
  51. X# First print guide-odd.ps, then find out which of the others to use.
  52. X# guide-even1.ps is for printers with correct output stacking like
  53. X# Apple LaserWriter II. 
  54. X# guide-even2.ps for printers with reverse output stacking, like old
  55. X# Apple LaserWriters. 
  56. X
  57. Xguide-odd.ps:    refbase.ps parr
  58. X    perl ./parr $(PAPER) \
  59. X        -o 21,2,19,4,17,6,15,8,13,10 refbase.ps > guide-odd.ps
  60. X
  61. Xguide-even1.ps:    refbase.ps parr
  62. X    perl ./parr $(PAPER) \
  63. X        -o 11,12,9,14,7,16,5,18,3,20 refbase.ps > guide-even1.ps
  64. X
  65. Xguide-even2.ps:    refbase.ps parr
  66. X    perl ./parr $(PAPER) \
  67. X        -o 3,20,5,18,7,16,9,14,11,12 refbase.ps > guide-even2.ps
  68. X
  69. Xguide-test.ps:    refbase.ps parr
  70. X    perl ./parr $(PAPER) \
  71. X        -o 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21 refbase.ps > guide-test.ps
  72. X
  73. Xclean:
  74. X    rm -f refguide.ps guide-odd.ps guide-even1.ps guide-even2.ps \
  75. X        refbase.dvi core *~
  76. X
  77. X# For maintenance use only ...
  78. X
  79. XVER    = 4.035
  80. X
  81. XCH    = ch00.tex ch01.tex ch02.tex ch03.tex ch04.tex ch05.tex \
  82. X      ch06.tex ch07.tex ch08.tex ch09.tex ch10.tex ch11.tex \
  83. X      ch12.tex ch13.tex ch14.tex ch15.tex ch16.tex ch17.tex \
  84. X      ch18.tex ch19.tex ch20.tex ch21.tex ch22.tex ch23.tex \
  85. X      ch24.tex ch25.tex ch26.tex ch27.tex \
  86. X      ch99.tex
  87. XSRC    = refbase.tex refbase.sty
  88. XAUX    = README ChangeLog Makefile parr Layout
  89. X
  90. X# Our TeX places its output here, never mind if yours doesn't.
  91. XTEXTMP = /usr/tmp/$(USER)TeX.
  92. X
  93. X# NOTE: DO NOT REMOVE OR CHANGE '-ta4' EVEN IF USING NON-A4 PAPER
  94. Xrefbase-ps:    refbase.dvi
  95. X    $(DVIPS) -r0 -ta4 refbase.dvi 
  96. X
  97. X#    -if [ -f psneat.pl ]; then \
  98. X#        mv refbase.ps refbase.ps~; \
  99. X#        perl ./psneat.pl refbase.ps~ > refbase.ps; \
  100. X#    else true; \
  101. X#    fi
  102. X
  103. Xrefbase.dvi:    $(SRC)
  104. X    $(LATEX) refbase.tex < /dev/null
  105. X    -if [ -f $(TEXTMP)dvi ]; then \
  106. X        mv $(TEXTMP)dvi refbase.dvi; \
  107. X    else true; \
  108. X    fi
  109. X
  110. XMASTER  = ref
  111. Xrefbase-tex:  $(MASTER)master.tex $(CH) makebase.pl
  112. X    perl ./makebase.pl $(REV) $(MASTER)master.tex > refbase.tex
  113. X
  114. Xkit:    
  115. X    REV=`cat Revision.SEQ`; \
  116. X    expr $$REV + 1 >Revision.SEQ; \
  117. X    (echo ""; echo Revision: $(VER).$$REV; what $(SRC) $(CH)) >> Revision; \
  118. X    $(MAKE) -$(MAKEFLAGS) REV=$$REV refbase-tex refbase-ps kitinternal
  119. X
  120. Xkitinternal:
  121. X    rm -f perlref_shr.* perlref_ltx.* perlref-$(VER).$(REV).tar.Z
  122. X    shar -c -n perlref-$(VER).$(REV) -a -s 'jv@mh.nl' \
  123. X        -o perlref-$(VER).$(REV)_shr -L30 -f $(AUX) refbase.ps
  124. X    shar -c -n perlltx-$(VER).$(REV) -a -s 'jv@mh.nl' \
  125. X        -o perlref-$(VER).$(REV)_ltx -L30 -f $(AUX) $(SRC)
  126. X    pdtar -zcvf perlref-$(VER).$(REV).tar.Z $(AUX) $(SRC) refbase.ps
  127. X    ls -l perlref-*_shr.* perlref-*_ltx.* perlref-*.tar.Z
  128. X
  129. Xident:
  130. X    what $(AUX) $(SRC)
  131. END_OF_FILE
  132.   if test 3058 -ne `wc -c <'Makefile'`; then
  133.     echo shar: \"'Makefile'\" unpacked with wrong size!
  134.   fi
  135.   # end of 'Makefile'
  136. fi
  137. if test -f 'refbase.tex' -a "${1}" != "-c" ; then 
  138.   echo shar: Will not clobber existing file \"'refbase.tex'\"
  139. else
  140.   echo shar: Extracting \"'refbase.tex'\" \(48498 characters\)
  141.   sed "s/^X//" >'refbase.tex' <<'END_OF_FILE'
  142. X\def\revision{1}
  143. X\documentstyle{refbase}
  144. X
  145. X\begin{document}
  146. X
  147. X
  148. X\begin{titlepage}
  149. X
  150. X\hbox{ }
  151. X\end{titlepage}
  152. X
  153. X\begin{titlepage}
  154. X\addtolength{\evensidemargin}{2cm}
  155. X\addtolength{\textwidth}{-2.1cm}
  156. X\vspace*{2.5cm}
  157. X
  158. X\unnumbered{Perl Reference Guide}
  159. X{\bf for Perl version \perlrev}
  160. X
  161. X\vskip1cm
  162. XPerl program designed and created by \\
  163. XLarry Wall \<lwall@netlabs.com\>
  164. X
  165. X\vskip1cm
  166. XReference guide designed and created by \\
  167. XJohan Vromans \<jv@mh.nl\>
  168. X
  169. X\vskip1.3cm
  170. X\unnumbered{Contents}
  171. X
  172. X\newcounter{xx}
  173. X\begin{list}{\thexx.}
  174. X{\setlength{\topsep}{0pt plus 1pt}
  175. X \setlength{\itemsep}{0pt plus 1pt}
  176. X \setlength{\parsep}{0pt plus 1pt}
  177. X \usecounter{xx}}
  178. X\item Command line options
  179. X\item Literals
  180. X\item Variables
  181. X\item Statements
  182. X\item Flow control
  183. X\item Operators
  184. X\item File test operators
  185. X\item Arithmetic functions
  186. X\item Conversion functions
  187. X\item Structure conversion
  188. X\item String functions
  189. X\item Array and list functions
  190. X\item File operations
  191. X\item Directory reading routines
  192. X\item Input / Output
  193. X\item Search and replace functions
  194. X\item System interaction
  195. X\item Networking
  196. X\item SystemV IPC
  197. X\item Miscellaneous
  198. X\item Formats
  199. X\item Info from system files
  200. X\item Regular expressions
  201. X\item Special variables
  202. X\item Special arrays
  203. X\item The perl debugger
  204. X\item Environment variables
  205. X\end{list}
  206. X\vskip1cm
  207. X{\catcode`\%=\other \small {Rev. \refrev}}
  208. X\end{titlepage}
  209. X
  210. X\unnumbered{Conventions}
  211. X
  212. X\begin{enum}{2cm}
  213. X\Xi{|fixed|} denotes literal text.
  214. X
  215. X\Xi{<this>} means variable text, i.e. things you must fill in.
  216. X
  217. X\Xi{<this>\dag} means that <this> will default to |$_| if omitted.
  218. X
  219. X\Xi{\kwd{word}} is a keyword, i.e. a word with a special meaning.
  220. X
  221. X\Xi{\fbox{<ret>}} denotes pressing a keyboard key.
  222. X
  223. X\Xi{[\ldots]} denotes an optional part.
  224. X
  225. X\Xi{(\ldots)*} means that the parentheses may be omitted.
  226. X
  227. X\end{enum}
  228. X
  229. X
  230. X\section{Command line options} 
  231. X
  232. X\begin{enum}{1cm}
  233. X
  234. X\Xi{|-a|} turns on autosplit mode when used with |-n| or
  235. X|-p|. Splits to |@F|.
  236. X
  237. X\Xi{|-c|} checks syntax but does not execute.
  238. X
  239. X\Xi{|-d|} runs the script under the debugger. Use |-de 0| to
  240. Xstart the debugger without a script.
  241. X
  242. X\Xi{|-D| <number>} sets debugging flags. 
  243. X
  244. X\Xi{|-e| <commandline>} may be used to enter one line of
  245. Xscript. Multiple |-e| commands may be given to build up a
  246. Xmulti-line script.
  247. X
  248. X\Xi{|-i| <ext>} files processed by the |<>| construct are
  249. Xto be edited in-place.
  250. X
  251. X\Xi{|-I| <dir>} with |-P|: tells the C preprocessor where
  252. Xto look for include files. The directory is prepended to |@INC|.
  253. X
  254. X\Xi{|-l| [ <octnum> ] } enables automatic line ending processing, e.g. |-l013|.
  255. X
  256. X\Xi{|-n|} assumes an input loop around your script. Lines are not
  257. Xprinted.
  258. X
  259. X\Xi{|-p|} assumes an input loop around your script. Lines are
  260. Xprinted.
  261. X
  262. X\Xi{|-P|} runs the C preprocessor on the script before
  263. Xcompilation by perl.
  264. X
  265. X\Xi{|-s|} interprets ``|-xxx|'' on the command line as
  266. Xswitches and sets the corresponding variables \$|xxx| in the script.
  267. X
  268. X\Xi{|-S|} uses the |PATH| environment variable to search for
  269. Xthe script.
  270. X
  271. X\Xi{|-u|} dumps core after compiling the script. To be used with
  272. Xthe {\it undump\/} program (where available).
  273. X
  274. X\Xi{|-U|} allows perl to do unsafe operations.
  275. X
  276. X\Xi{|-v|} prints the version and patchlevel of your perl
  277. Xexecutable.
  278. X
  279. X\Xi{|-w|} prints warnings about possible spelling errors and
  280. Xother error-prone constructs in the script.
  281. X
  282. X\Xi{|-x|} extracts perl program from input stream.
  283. X
  284. X\Xi{|-0| <val>} (that's the number zero) designates an
  285. Xinitial value for the record terminator \$|/|.
  286. XSee also |-l|.
  287. X
  288. X\end{enum}
  289. X
  290. X\makeuppage
  291. X
  292. X\section{Literals} 
  293. X
  294. XNumeric: |123  1_234  123.4  5E-10  0xff| (hex)|  0377| (octal).
  295. X
  296. X\hangindent=2cm\hangafter=1
  297. XString: |'abc'| literal string, no variable interpolation nor
  298. Xescape characters.
  299. X\newline Also: |q/abc/|.
  300. X\newline (Almost any pair of delimiters can be used instead of |/.../|.)
  301. X
  302. X\hangindent=2cm\hangafter=1
  303. X\makebox[1cm]{}|"abc"|
  304. XVariables are interpolated and escape sequences are processed. 
  305. X\newline Also: |qq/abc/|.
  306. X\newline Escape sequences: |\t| (Tab), |\n| (Newline), |\r| (Return),
  307. X|\f| (Formfeed), |\b| (Backspace), |\a| (Alarm), |\e|
  308. X(Escape), |\033|(octal), |\x1b|(hex), |\c[| (control).
  309. X\newline |\l| and |\u| lowcase/upcase the following character; 
  310. X\newline |\L| and |\U| lowcase/upcase until a |\E| is encountered.
  311. X
  312. X
  313. X\hangindent=2cm\hangafter=1
  314. X\makebox[1cm]{}|`|<command>|`|
  315. Xevaluates to the output of the <command>. 
  316. X\newline Also: |qx/|<command>|/|.
  317. X
  318. X\hangindent=1cm\hangafter=1
  319. XArray: |(1,2,3)|. |()| is an empty array.  
  320. X\newline Also: |($a,$b,@rest) = (1,2,...);|
  321. X\newline |(1..4)| is the same as |(1,2,3,4)|. Likewise |('abc'..'ade')|
  322. X
  323. X\hangindent=1cm\hangafter=1
  324. XAssociative array:
  325. X|(|<key1>|,|<val1>|,|<key2>|,|<val2>|,...)|
  326. X
  327. X\hangindent=1cm\hangafter=1
  328. XFilehandles: 
  329. X\newline Pre-defined: |<STDIN>|, |<STDOUT>|, |<STDERR>|, |<ARGV>|,
  330. X|<DATA>|;
  331. X\newline User-specified: |<|<handle>|>|, |<$|<var>|>|.
  332. X\newline |<>| is the input stream formed by the files specified in
  333. X|@ARGV|, or standard input if no arguments are supplied.
  334. X
  335. X\hangindent=1cm\hangafter=1
  336. XGlobs: |<|<pattern>|>| evaluates to all filenames according
  337. Xto the pattern.
  338. X\newline Use |<${|<var>|}>| to glob from a variable.
  339. X
  340. X\hangindent=1cm\hangafter=1
  341. XHere-Is: |<<|<identifier>
  342. X\newline {\it See the manual for details.}
  343. X
  344. X\hangindent=1cm\hangafter=1
  345. XSpecial tokens:
  346. X\newline \_\,\_|FILE|\_\,\_: filename; \_\,\_|LINE|\_\,\_: line number.
  347. X\newline \_\,\_|END|\_\,\_: end of program; remaining lines can be read using
  348. X\<<data>\>.
  349. X
  350. X
  351. X\section{Variables} 
  352. X
  353. X\begin{enum}{3.2cm}
  354. X
  355. X\Xi{|\$var|} a simple scalar variable
  356. X
  357. X\Xi{|\$var[28]|} 29th element of array |@var| (the |[]| are
  358. Xpart of it)
  359. X
  360. X\Xi{|\$var\{'Feb'\}|} one value from associative array |%var|
  361. X
  362. X\Xi{|\$\#var|} last index of array |@var|
  363. X
  364. X\Xi{|@var|} the entire array;
  365. X\\
  366. Xin scalar context: the number of elements in the array
  367. X
  368. X\Xi{|@var[3,4,5]|} a slice of the array |@var|
  369. X
  370. X\Xi{|@var\{'a','b'\}|} a slice of |%var|; same as
  371. X|($var{'a'},$var{'b'})|
  372. X
  373. X\Xi{|\%var|} the entire associative array;
  374. X\\
  375. Xin scalar context: TRUE if the array has elements
  376. X
  377. X\Xj{|\$var\{'a',1,...\}|} emulates a multi-dimensional array
  378. X
  379. X\Xi{|('a'..'z')[4,7,9]|} a slice of an array literal
  380. X
  381. X\Xi{|*|<name>} refers to all objects represented by <name>.
  382. X``|*name1 = *name2|'' makes |name1| a reference to |name2|.
  383. X
  384. X\end{enum}
  385. X
  386. X
  387. X\section{Statements} 
  388. X
  389. XEvery statement is an expression, optionally followed by a modifier,
  390. Xand terminated by a semicolon.  The semicolon may be omitted if the
  391. Xstatement is the final one in a BLOCK.
  392. X
  393. XExecution of expressions can depend on other expressions using one of
  394. Xthe modifiers \kwd{if}, \kwd{unless}, \kwd{while} or \kwd{until},
  395. Xe.g.:
  396. X
  397. X\quad    <expr1> \kwd{if} <expr2> |;| \\
  398. X\quad    <expr1> \kwd{until} <expr2> |;|
  399. X
  400. XAlso, by using one of the logical operators \|\|, |&&| or |? :|, e.g.:
  401. X
  402. X\quad    <expr1> \|\| <expr2> |;| \\
  403. X\quad    <expr1> |?| <expr2> |:| <expr3> |;| 
  404. X
  405. XStatements can be combined to form a <block> when enclosed in |{}|.
  406. X
  407. XCompound statements may be used to control flow:
  408. X
  409. X\quad    \kwd{if} |(|<expr>|)| <block> [ [ \kwd{elsif}
  410. X    |(|<expr>|)| <BLOCK ...> ] \kwd{else}
  411. X    <block> ]
  412. X\\
  413. X\quad    \kwd{unless} |(|<expr>|)| <block> [ \kwd{else}
  414. X    <block> ]
  415. X\\
  416. X\quad    [ <label>\kwd{:} ] \kwd{while} |(|<expr>|)|
  417. X    <block> [ \kwd{continue} <block> ]
  418. X\\
  419. X\quad    [ <label>\kwd{:} ] \kwd{until} |(|<expr>|)|
  420. X    <block> [ \kwd{continue} <block> ]
  421. X\\
  422. X\quad    [ <label>\kwd{:} ] \kwd{for} |(|<expr>|;|
  423. X    <expr>|;| <expr>|)| <block>
  424. X\\
  425. X\quad    [ <label>\kwd{:} ] \kwd{foreach} <var>\dag
  426. X    |(|<array>|)| <block>
  427. X\\
  428. X\quad    [ <label>\kwd{:} ] <block> [ \kwd{continue} < block> ]
  429. X
  430. XSpecial forms are:
  431. X
  432. X\quad    \kwd{do} <block> \kwd{while} <expr> |;| \\
  433. X\quad    \kwd{do} <block> \kwd{until} <expr> |;| \\
  434. X
  435. Xwhich are guaranteed to perform <block> once before testing <expr>.
  436. X
  437. X
  438. X
  439. X\section{Flow control} 
  440. X
  441. X\begin{enum}{1cm}
  442. X
  443. X\Xi{\kwd{do} <block>}
  444. XReturns the value of the last command in the sequence of commands indicated by <block>. \kwd{next}, \kwd{last} and \kwd{redo}
  445. X cannot be used here.
  446. X
  447. X\Xi{\kwd{do} <subroutine>\kwd{(LIST)}} 
  448. XExecutes a <subroutine> declared by a \kwd{sub} declaration, and
  449. Xreturns the value of the last expression evaluated in <subroutine> .
  450. X\newline Preferred form is: |&|<subroutine> .
  451. X
  452. X\Xi{\kwd{do} <FILENAME>}
  453. XExecutes the contents of <filename> as a perl script. Errors are
  454. Xreturned in |$@|.
  455. X\newline Preferred form is: \kwd{require} <filename> .
  456. X
  457. X\Xi{\kwd{goto} <label>}
  458. XContinue execution at the specified label.
  459. X
  460. X\Xi{\kwd{last} [<label>]}
  461. XImmediately exits the loop in question. Skips continue block.
  462. X
  463. X\Xi{\kwd{next} [<label>]}
  464. XStarts the next iteration of the loop.
  465. X
  466. X\Xi{\kwd{redo} [<label>]}
  467. XRestarts the loop block without evaluating the conditional again.
  468. X
  469. X\Xi{\kwd{return} <expr>}
  470. XReturns from a subroutine with the value specified.
  471. X
  472. X\end{enum}
  473. X
  474. X
  475. X\section{Operators} 
  476. X
  477. X\begin{tabbing}
  478. X|    |\=|    |\= \kill
  479. X|+ -| \> |* /| \> Addition, subtraction, multiplication, division. \\
  480. X|%| \> \> Modulo division. \\
  481. X\| \& \> \^ \> Bitwise or, bitwise and, bitwise exclusive or. \\
  482. X|>>| \> |<<| \> Bitwise shift right, bitwise shift left. \\
  483. X|**| \> \> Exponentiation. \\
  484. X|.| \> \> Concatenation of two strings. \\
  485. X\kwd{x} \> \> Returns a string or array consisting of the left operand
  486. X(an array or \\
  487. X\> \> a string) repeated the number of times specified by the right operand.
  488. X\end{tabbing}
  489. X
  490. XAll of the above operators also have an assignment operator, e.g. ``|.=|''.
  491. X
  492. X\begin{tabbing}
  493. X|    |\=|    |\= \kill
  494. X|++| \> |--| \> Auto-increment (magical on strings), auto-decrement. \\
  495. X|? :|\>      \> Alternation (if-then-else) operator. \\
  496. X\|\| \> \&\&   \> Logical or, logical and. \\
  497. X|=|\,|=| \> |!=| \> Numeric equality, inequality. \\
  498. X\kwd{eq} \> \kwd{ne} \> String equality, inequality. \\
  499. X|<|  \>  |>|  \> Numeric less than, greater than. \\
  500. X\kwd{lt} \> \kwd{gt} \> String less than, greater than. \\
  501. X|<=| \> |>=| \> Numeric less (greater) than or equal to. \\
  502. X\kwd{le} \> \kwd{ge} \> String less (greater) than or equal. \\
  503. X|<=>| \> \> Numeric compare. Returns -1, 0 or 1. \\
  504. X\kwd{cmp} \> \> String compare. Returns -1, 0 or 1. \\
  505. X|=~| \> |!~| \> Search pattern, substitution, or translation (negated). \\
  506. X|..| \> \> Enumeration, also input line range operator. \\
  507. X|,| \> \> Comma operator.
  508. X\end{tabbing}
  509. X
  510. X
  511. X\section{File test operators} 
  512. X
  513. XThese unary operators takes one argument, either a filename or a
  514. Xfilehandle, and tests the associated file to see if something is true
  515. Xabout it. If the argument is omitted, tests |$_| (except for |-t,|
  516. Xwhich tests |STDIN|). If the special argument |_| (underscore) is
  517. Xpassed, uses the info of the preceding test. 
  518. X
  519. X\begin{enum}{2.5cm}
  520. X
  521. X\Xi{|-r -w -x|}  File is readable/writable/executable by effective uid/gid.
  522. X
  523. X\Xi{|-R -W -X|}  File is readable/writable/executable by real uid/gid.
  524. X
  525. X\Xi{|-o  -O|}  File is owned by effective/real uid. 
  526. X
  527. X\Xi{|-e  -z|}  File exists / has zero size. 
  528. X
  529. X\Xi{|-s|}  File exists and has non-zero size. Returns the size.
  530. X
  531. X\Xi{|-f  -d|}  File is a plain file, a directory.
  532. X
  533. X\Xi{|-l  -S  -p|}  File is a symbolic link, a socket, a named pipe (FIFO). 
  534. X
  535. X\Xi{|-b  -c|}  File is a block/character special file. 
  536. X
  537. X\Xi{|-u  -g  -k|}  File has setuid/setgid/sticky bit set. 
  538. X
  539. X\Xi{|-t|}  Tests if filehandle (|STDIN| by default) is opened to a tty.
  540. X
  541. X\Xi{|-T  -B|}  File is a text/non-text (binary) file.  |-T| and |-B|
  542. Xreturn TRUE on a null file, or a file at EOF when testing a filehandle. 
  543. X
  544. X\Xi{|-M  -A  -C|}  File creation / access / inode change time. Measured
  545. Xin days since this program started. See also |$^T| in section
  546. X``Special~Variables''.
  547. X
  548. X\end{enum}
  549. X
  550. X\makeuppage
  551. X
  552. XA <list> is a (possibly parenthesised) list of expressions, variables
  553. Xor <list>s. An array variable or an array slice may always be used
  554. Xinstead of a <list>.  
  555. X
  556. X\section{Arithmetic functions} 
  557. X
  558. X\begin{enum}{1cm}
  559. X
  560. X\Xi{\kwd{atan2(}<y>\kwd{,}<x>\kwd{)}}
  561. XReturns the arctangent of <Y>/<X> in the range -$\pi$ to $\pi$.
  562. X
  563. X\Xi{\kwd{cos(}\oEXPR \kwd{)}*}
  564. XReturns the cosine of <expr> (expressed in radians).
  565. X
  566. X\Xi{\kwd{exp(}\oEXPR \kwd{)}*}
  567. XReturns |e| to the power of <expr>.
  568. X
  569. X\Xi{\kwd{int(}\oEXPR \kwd{)}*}
  570. XReturns the integer portion of <expr>.
  571. X
  572. X\Xi{\kwd{log(}\oEXPR \kwd{)}*}
  573. XReturns natural logarithm (base |e|) of <expr>.
  574. X
  575. X\Xi{\kwd{rand}[\kwd{(}<expr>\kwd{)}*]}
  576. XReturns a random fractional number between 0 and the value of <expr>.
  577. XIf <expr> is omitted, returns a value between 0 and 1. 
  578. X
  579. X\Xi{\kwd{sin(}\oEXPR \kwd{)}*}
  580. XReturns the sine of <expr> (expressed in radians).
  581. X
  582. X\Xi{\kwd{sqrt(}\oEXPR \kwd{)}*}
  583. XReturn the square root of <expr>.
  584. X
  585. X\Xi{\kwd{srand}[\kwd{(}<expr>\kwd{)}*]}
  586. XSets the random number seed for the rand operator.
  587. X
  588. X\Xi{\kwd{time}}
  589. XReturns the number of seconds since January 1, 1970. Suitable for
  590. Xfeeding to \kwd{gmtime} and \kwd{localtime}. 
  591. X
  592. X\end{enum}
  593. X
  594. X
  595. X\section{Conversion functions} 
  596. X
  597. X\begin{enum}{1cm}
  598. X
  599. X\Xi{\kwd{gmtime(}<expr>\kwd{)}*}
  600. XConverts a time as returned by the \kwd{time} function to a 9-element
  601. Xarray (\$sec, \$min, \$hour, \$mday, \$mon, \$year, \$wday,
  602. X\$yday, \$isdst) with the time analyzed for the Greenwich timezone.
  603. X\$mon has the range 0..11 and \$wday has the range 0..6.
  604. X
  605. X\Xi{\kwd{hex(}\oEXPR\kwd{)}*}
  606. XReturns the decimal value of <expr> interpreted as an hex string.
  607. X
  608. X\Xi{\kwd{localtime(}<expr>\kwd{)}*}
  609. XConverts a time as returned by the \kwd{time} function to a 9-element
  610. Xarray with the time analyzed for the local timezone. 
  611. X
  612. X\Xi{\kwd{oct(}\oEXPR\kwd{)}*}
  613. XReturns the decimal value of <expr> interpreted as an octal string. If
  614. X<expr> starts off with |0x|, interprets it as a hex string instead.
  615. X
  616. X\Xi{\kwd{ord(}\oEXPR\kwd{)}*}
  617. XReturns the ascii value of the first character of <expr>.
  618. X
  619. X\Xi{\kwd{vec(}<expr>\kwd{,}<offset>\kwd{,}<bits>\kwd{)}}
  620. XTreats <expr> as a string of unsigned ints, and yields the bit at
  621. X<offset>. <bits> must be between 1 and 32. May be used as an lvalue.
  622. X
  623. X\end{enum}
  624. X
  625. X
  626. X\section{Structure conversion} 
  627. X
  628. X\begin{enum}{1cm}
  629. X
  630. X\Xi{\kwd{pack(}<template>\kwd{,}<list>\kwd{)}}
  631. XPacks the values into a binary structure using <template>.
  632. X
  633. X\Xi{\kwd{unpack(}<template>\kwd{,}<expr>\kwd{)}}
  634. XUnpacks the structure <expr> into an array, using <template>.
  635. X
  636. X<template> is a sequence of characters as follows:
  637. X
  638. X\begin{tabbing}
  639. X|  |\=|a |\=|/ |\=|A  |\= \kill
  640. X  \> |a| \> / \> |A| \> Ascii string, null / space padded \\
  641. X  \> |b| \> / \> |B| \> Bit string in ascending / descending order \\
  642. X  \> |c| \> / \> |C| \> Native / unsigned char value \\
  643. X  \> |f| \> / \> |d| \> Single / double float in native format \\
  644. X  \> |h| \> / \> |H| \> Hex string, low / high nybble first. \\
  645. X  \> |i| \> / \> |I| \> Signed / unsigned integer value \\
  646. X  \> |l| \> / \> |L| \> Signed / unsigned long value \\
  647. X  \> |n| \> / \> |N| \> Short / long in network (big endian) byte order \\
  648. X  \> |s| \> / \> |S| \> Signed / unsigned short value \\
  649. X  \> |u| \> / \> |p| \> Uuencoded string / Pointer to a string \\
  650. X  \> |v| \> / \> |V| \> Short / long in VAX (little endian) byte order \\
  651. X  \> |x| \> / \> |@| \> Null byte / null fill until position \\
  652. X  \> |X| \>   \>     \> Backup a byte
  653. X\end{tabbing}
  654. X
  655. XEach character may be followed by a decimal number which will be used
  656. Xas a repeat count, an |*| specifies all remaining arguments. \\
  657. XIf the format is preceded with |%|<n>, \kwd{unpack} returns an
  658. X<n>-bit checksum instead. \\
  659. XSpaces may be included in the template for readability purposes.
  660. X
  661. X\end{enum}
  662. X
  663. X
  664. X\section{String functions} 
  665. X
  666. X\begin{enum}{1cm}
  667. X
  668. X\Xi{\kwd{chop(}<list>\dag\kwd{)}}
  669. XChops off the last character on all elements of the list; returns the
  670. Xlast chopped character. The parentheses may be omitted if <list> is a
  671. Xsingle variable.
  672. X
  673. X\Xi{\kwd{crypt(}<plaintext>\kwd{,}<salt>\kwd{)}}
  674. XEncrypts a string.
  675. X
  676. X\Xi{\kwd{eval(}\oEXPR \kwd{)}*}
  677. X<expr> is parsed and executed as if it were a perl program. The value
  678. Xreturned is the value of the last expression evaluated. If there is a
  679. Xsyntax error or runtime error, an undefined string is returned by
  680. X\kwd{eval}, and |$@| is set to the error message.
  681. X
  682. X\Xi{\kwd{eval\{}<expr>\kwd{;...\}}}
  683. XExecutes the code between \{ and \}. Traps runtime errors as described
  684. Xabove.
  685. X
  686. X\Xi{\kwd{index(}<str>\kwd{,}<substr>[\kwd{,}<offset>]\kwd{)}}
  687. XReturns the position of <substr> in <str> at or after <offset>. If the
  688. Xsubstring is not found, returns |$[-1|.
  689. X
  690. X\Xi{\kwd{length(}\oEXPR\kwd{)}*}
  691. XReturns the length in characters of the value of <expr>.
  692. X
  693. X\Xi{\kwd{rindex(}<str>\kwd{,}<substr>[\kwd{,}<offset>]\kwd{)}}
  694. XReturns the position of the last <substr> in <str> at or
  695. Xbefore <offset>.
  696. X
  697. X\Xi{\kwd{substr(}<expr>\kwd{,}<offset>[\kwd{,}<len>]\kwd{)}}
  698. XExtracts a substring out of <expr> and returns it. If <offset>
  699. Xis negative, counts from the end of the string. May be used as an lvalue.
  700. X
  701. X\end{enum}
  702. X
  703. X\makeuppage
  704. X
  705. X\section{Array and list functions} 
  706. X
  707. X\begin{enum}{1cm}
  708. X
  709. X\Xi{\kwd{delete} \$<array>\{<key>\}}
  710. XDeletes the specified value from the specified associative array.
  711. XReturns the deleted value. 
  712. X
  713. X\Xi{\kwd{each(}|\%|<array>\kwd{)}*}
  714. XReturns a 2-element array consisting of the key and value for the next
  715. Xvalue of an associative array. Entries are returned in an apparently
  716. Xrandom order. When the array is entirely read, a null array is
  717. Xreturned. The next call to \kwd{each} after that will start iterating again.
  718. X
  719. X\Xi{\kwd{grep(}<expr>\kwd{,}<list>\kwd{)}}
  720. XEvaluates <expr> for each element of the <list>, locally setting |$_|
  721. Xto refer to the element. Modifying |$_| will modify the corresponding
  722. Xelement from <list>. Returns array of elements from <list> for which
  723. X<expr> returned true. 
  724. X
  725. X\Xi{\kwd{join(}<expr>\kwd{,}<list>\kwd{)}}
  726. XJoins the separate strings of <list> into a single string with fields
  727. Xseparated by the value of <expr>, and returns the string.
  728. X
  729. X\Xi{\kwd{keys(}|\%|<array>\kwd{)}*}
  730. XReturns an array with of all the keys of the named
  731. Xassociative array.
  732. X
  733. X\Xi{\kwd{pop(}|@|<array>\kwd{)}*}
  734. XPops and returns the last value of the array, shortens the array by 1. 
  735. X
  736. X\Xi{\kwd{push(}|@|<array>\kwd{,}<list>\kwd{)}}
  737. XPushes the values of <list> onto the end of <array>. The length of the
  738. Xarray increases by the length of <list>.
  739. X
  740. X\Xi{\kwd{reverse(}<list>\kwd{)}*}
  741. XIn array context: returns the <list> in reverse order. \\
  742. XIn scalar
  743. Xcontext: returns the first element of <list> with bytes reversed. 
  744. X
  745. X\Xi{\kwd{scalar(}|@|<array>\kwd{)}}
  746. XReturns the number of elements in the array.
  747. X
  748. X\Xi{\kwd{scalar(}|\%|<array>\kwd{)}}
  749. XReturns TRUE if the associative array has elements defined.
  750. X
  751. X\Xi{\kwd{shift}[\kwd{(}|@|<array>\kwd{)}*]}
  752. XShifts the first value of the array off and returns it, shortening the
  753. Xarray by 1 and moving everything down. If |@|<array> is omitted, shifts
  754. X|@ARGV| in main and |@_| in subroutines.  
  755. X
  756. X\Xi{\kwd{sort(} [<subroutine> ] <list>\kwd{)}*}
  757. XSorts the <list> and returns the sorted array value. If <subroutine>
  758. Xis specified, gives the name of a subroutine that returns less than
  759. Xzero, zero, or greater than zero, depending on how the elements of the
  760. Xarray, available to the routine as |$a| and |$b|, are to be ordered.
  761. X\\
  762. X<SUBROUTINE> may be the name of a user-defined routine, or a <block>
  763. X(see ``Statements'' and ``Miscellaneous'').
  764. X
  765. X\Xi{\kwd{splice(}|@|<array>\kwd{,}<offset>[\kwd{,}<length>[\kwd{,}<list>]]\kwd{)}}
  766. XRemoves the elements of |@|<array> designated by <offset> and
  767. X<length>, and replaces them with <list> (if specified). \\
  768. XReturns the elements removed.
  769. X
  770. X\Xi{\kwd{split}[\kwd{(}<pattern>[\kwd{,}\oEXPR [\kwd{,}<limit>]]\kwd{)}]}
  771. XSplits a string into an array of strings, and returns it. If <limit>
  772. Xis specified, splits in no more than that many fields. If <pattern> is
  773. Xalso omitted, splits on whitespace. If
  774. Xnot in array context: returns number of fields and splits to |@_|.
  775. XSee also: ``Search and Replace Functions''. 
  776. X
  777. X\Xi{\kwd{unshift(}|@|<array>\kwd{,}<list>\kwd{)}}
  778. XPrepends list to the front of the array, and returns the number of
  779. Xelements in the new array.
  780. X
  781. X\Xi{\kwd{values(}|\%|<array>\kwd{)}*}
  782. XReturns a normal array consisting of all the values of the named
  783. Xassociative array. 
  784. X
  785. X\end{enum}
  786. X
  787. X
  788. X
  789. X\makeupspace{1cm}
  790. X
  791. X\section{File operations} 
  792. X
  793. XFunctions operating on a list of files return the number of files
  794. Xsuccessfully operated upon.
  795. X
  796. X\begin{enum}{1cm}
  797. X
  798. X\Xi{\kwd{chmod(}<list>\kwd{)}*}
  799. XChanges the permissions of a list of files. The first element of the
  800. Xlist must be the numerical mode. 
  801. X
  802. X\Xi{\kwd{chown(}<list>\kwd{)}*}
  803. XChanges the owner and group of a list of files. The first two elements
  804. Xof the list must be the numerical uid and gid. 
  805. X
  806. X\Xi{\kwd{truncate(}<file>\kwd{,}<size>\kwd{)}}
  807. Xtruncates <file> to <size>. <file> may be a filename or a filehandle.
  808. X
  809. X\Xi{\kwd{link(}<oldfile>\kwd{,}<newfile>\kwd{)}}
  810. XCreates a new filename linked to the old filename.
  811. X
  812. X\Xi{\kwd{lstat(}<file>\kwd{)}}
  813. XLike stat, but does not traverse a final symbolic link.
  814. X
  815. X\Xi{\kwd{mkdir(}<dir>\kwd{,}<mode>\kwd{)}}
  816. XCreates a directory with given permissions. Sets |$!| on failure.
  817. X
  818. X\Xi{\kwd{readlink(}\oEXPR\kwd{)}*}
  819. XReturns the value of a symbolic link.
  820. X
  821. X\Xi{\kwd{rename(}<oldname>\kwd{,}<newname>\kwd{)}}
  822. XChanges the name of a file.
  823. X
  824. X\Xi{\kwd{rmdir(}<filename>\dag\kwd{)}*}
  825. XDeletes the directory if it is empty. Sets |$!| on failure.
  826. X
  827. X\Xi{\kwd{stat(}<file>\kwd{)}}
  828. XReturns a 13-element array (\$dev, \$ino, \$mode, \$nlink, \$uid, \$gid,
  829. X\$rdev, \$size, \$atime, \$mtime, \$ctime, \$blksize, \$blocks). <file> can
  830. Xbe a filehandle, an expression evaluating to a filename, or |_| to
  831. Xrefer to the last file test operation. 
  832. X\\
  833. XReturns a null list if the \kwd{stat} fails.
  834. X
  835. X\Xi{\kwd{symlink(}<oldfile>\kwd{,}<newfile>\kwd{)}}
  836. XCreates a new filename symbolically linked to the old filename.
  837. X
  838. X\Xi{\kwd{unlink(}<list>\kwd{)}*}
  839. XDeletes a list of files.
  840. X
  841. X\Xi{\kwd{utime(}<list>\kwd{)}*}
  842. XChanges the access and modification times. The first two elements of
  843. Xthe list must be the numerical access and modification times.
  844. X
  845. X\end{enum}
  846. X
  847. X
  848. X
  849. X\makeuppage
  850. X
  851. X\section{Directory reading routines} 
  852. X
  853. X\begin{enum}{1cm}
  854. X
  855. X\Xi{\kwd{closedir(}<dirhandle>\kwd{)}*}
  856. XCloses a directory opened by opendir.
  857. X
  858. X\Xi{\kwd{opendir(}<dirhandle>\kwd{,}<dirname>\kwd{)}}
  859. XOpens a directory on the handle specified.
  860. X
  861. X\Xi{\kwd{readdir(}<dirhandle>\kwd{)}*}
  862. XReturns the next entry (or an array of entries) in the directory.
  863. X
  864. X\Xi{\kwd{rewinddir(}<dirhandle>\kwd{)}*}
  865. XPositions the directory to the beginning.
  866. X
  867. X\Xi{\kwd{seekdir(}<dirhandle>\kwd{,}<pos>\kwd{)}}
  868. XSets position for readdir on the directory.
  869. X
  870. X\Xi{\kwd{telldir(}<dirhandle>\kwd{)}*}
  871. XReturns the postion in the directory.
  872. X
  873. X\end{enum}
  874. X
  875. X
  876. X\section{Input / Output} 
  877. X
  878. XIn input/output operations, <filehandle> may be a filehandle as opened
  879. Xby the \kwd{open} operator, or a scalar variable which evaluates to
  880. Xthe name of a filehandle to be used.  
  881. X
  882. X\begin{enum}{1cm}
  883. X
  884. X\Xi{\kwd{binmode(}<filehandle>\kwd{)}*}
  885. XArranges for the file opened on <filehandle> to be read in ``binary''
  886. Xmode as opposed to ``text'' mode (MS-DOS only). 
  887. X
  888. X\Xi{\kwd{close(}<filehandle>\kwd{)}*}
  889. XCloses the file or pipe associated with the file handle.
  890. X
  891. X\Xi{\kwd{dbmclose(}|\%|<array>\kwd{)}*}
  892. XBreaks the binding between the array and the dbm file.
  893. X
  894. X\Xi{\kwd{dbmopen(}|\%|<array>\kwd{,}<dbmname>\kwd{, }<mode>\kwd{)}}
  895. XBinds a dbm or ndbm file to the associative array. If the database
  896. Xdoes not exist, it is created with the indicated mode. 
  897. X
  898. X\Xi{\kwd{eof(}<filehandle>\kwd{)}}
  899. XReturns 1 if the next read will return end of file, or if the file is
  900. Xnot open. 
  901. X
  902. X\Xi{\kwd{eof}}
  903. XReturns the eof status for the last file read.
  904. X
  905. X\Xi{\kwd{eof( )}}
  906. XIndicates eof on the pseudo file formed of the files listed on the
  907. Xcommand line. 
  908. X
  909. X\Xi{\kwd{fcntl(}<filehandle>\kwd{,}<function>\kwd{,}|\$|<var>\kwd{)}}
  910. XImplements the {\it fcntl\/}(2) function. This function has non-standard
  911. Xreturn values. See the manual for details. 
  912. X
  913. X\Xi{\kwd{fileno(}<filehandle>\kwd{)}*}
  914. XReturns the file descriptor for a given (open) file.
  915. X
  916. X\Xi{\kwd{flock(}<filehandle>\kwd{,}<operation>\kwd{)}}
  917. XCalls {\it flock\/}(2) on the file. <operation> adds from 1 (shared), 2
  918. X(exclusive), 4 (non-blocking) or 8 (unlock). 
  919. X
  920. X
  921. X\Xi{\kwd{getc}[\kwd{(}<filehandle>\kwd{)}*]}
  922. XYields the next character from the file, or |""| on EOF. If
  923. X<filehandle> is omitted, reads from |STDIN|. 
  924. X
  925. X\Xi{\kwd{ioctl(}<filehandle>\kwd{,}<function>\kwd{,}|\$|<var>\kwd{)}}
  926. Xperforms {\it ioctl}(2) on the file. This function has non-standard
  927. Xreturn values. See the manual for details. 
  928. X
  929. X\Xi{\kwd{open(}<filehandle>[\kwd{,}<filename>]\kwd{)}}
  930. XOpens a file and associates it with <filehandle>. If <filename> is
  931. Xomitted, the scalar variable of the same name as the <filehandle> must
  932. Xcontain the filename.
  933. X
  934. XThe following filename conventions apply when opening a file.
  935. X
  936. X\begin{enum}{2cm}
  937. X\Xi{|"|<file>|"|} open <file> for input. Also |"<|<file>|"|.
  938. X
  939. X\Xi{|">|<file>|"|} open <file> for output, creating it if necessary.
  940. X
  941. X\Xi{|">>|<file>|"|} open <file> in append mode.
  942. X
  943. X\Xi{|"+>|<file>|"|} open <file> with read/write access.
  944. X
  945. X\Xi{|"\||<cmd>|"|} opens a pipe to command <cmd>.
  946. X
  947. X\Xi{|"|<cmd>|\|"|} opens a pipe from command <cmd>.
  948. X\end{enum}
  949. X
  950. X<file> may be |&|<filehnd> in which case the new file handle is
  951. Xconnected to the (previously opened) filehandle <filehnd>.
  952. X
  953. X\kwd{open} 
  954. Xreturns 1 upon success, \kwd{undef} otherwise, except for pipes. The
  955. Xparentheses may be omitted, if only a <filehandle> is specified.
  956. X
  957. X\Xi{\kwd{pipe(}<readhandle>\kwd{,}<writehandle>\kwd{)}}
  958. XReturns a pair of connected pipes.
  959. X
  960. X\Xi{\kwd{print}[\kwd{(}[<filehandle>]<list>\dag\kwd{)}*]}
  961. XPrints a string or a comma-separated list of strings. If <filehandle>
  962. Xis omitted, prints by default to standard output (or to the last
  963. Xselected output channel - see \kwd{select}).  
  964. X
  965. X\Xi{\kwd{printf}[\kwd{(}[<filehandle>] <list>\kwd{)}*]}
  966. XEquivalent to \kwd{print} <filehandle> \kwd {sprintf(}<list>\kwd{)}.
  967. X
  968. X\Xi{\kwd{read(}<filehandle>\kwd{,}|\$|<var>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  969. XRead <length> binary bytes from the file into the variable at
  970. X<offset>. Returns number of bytes actually read. 
  971. X
  972. X\Xi{\kwd{seek(}<filehandle>\kwd{,}<position>\kwd{,}<whence>\kwd{)}}
  973. XArbitrarily positions the file. Returns 1 upon success, 0 otherwise.
  974. X
  975. X\Xi{\kwd{select}[\kwd{(}<filehandle>\kwd{)}]}
  976. XReturns the currently selected filehandle. 
  977. XSets the current default filehandle for output operations if
  978. X<filehandle> is supplied.
  979. X
  980. X\Xi{\kwd{select(}<rbits>\kwd{,}<wbits>\kwd{,}<nbits>\kwd{,}<timeout>\kwd{)}}
  981. XPerforms a {\it select\/}(2) system call with the same parameters.
  982. X
  983. X\Xi{\kwd{sprintf(}<format>\kwd{,}<list>\kwd{)}}
  984. XReturns a string formatted by (almost all of) the usual printf
  985. Xconventions. 
  986. X
  987. X\Xi{\kwd{sysread(}<filehandle>\kwd{,}|\$|<var>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  988. XReads <length> bytes into |$|<var> at <offset>.
  989. X
  990. X\Xi{\kwd{syswrite(}<filehandle>\kwd{,}<scalar>\kwd{,}<length>[\kwd{,}<offset>]\kwd{)}}
  991. XWrites <length> bytes from <scalar> at <offset>.
  992. X
  993. X\Xi{\kwd{tell}[\kwd{(}<filehandle>\kwd{)}]*}
  994. XReturns the current file position for the file. If <filehandle> is
  995. Xomitted, assumes the file last read. 
  996. X
  997. X\Xi{\kwd{write}[\kwd{(}<filehandle>\kwd{)}]*}
  998. XWrites a formatted record to the specified file, using the format
  999. Xassociated with that file. See ``Formats''. 
  1000. X
  1001. X\end{enum}
  1002. X
  1003. X\makeuppage
  1004. X
  1005. X\section{Search and replace functions}
  1006. X
  1007. X\begin{enum}{1cm}
  1008. X
  1009. X\catcode`\~=\other
  1010. X
  1011. X\Xi{[<expr> |=~|] [\kwd{m}]|/|<pattern>|/|[\kwd{g}][\kwd{i}][\kwd{o}]}
  1012. XSearches <expr> (default: |$_|) for a pattern. If you prepend an
  1013. X\kwd{m} you can use almost any pair of characters as delimiters. If
  1014. Xused in array context, an array is returned consisting of the
  1015. Xsubexpressions matched by the parentheses in pattern, i.e.
  1016. X|($1,$2,$3,...)|.
  1017. X\\
  1018. XOptional modifiers: \kwd{g} matches as many times as possible; \kwd{i}
  1019. Xsearches in a case-insensitive manner; \kwd{o} interpolates variables
  1020. Xonly once.
  1021. X\\
  1022. XIf <pattern> is empty, the most recent pattern from a
  1023. Xprevious match or replacement is used.
  1024. X\\
  1025. XWith \kwd{g} the match can be used as an iterator in scalar context.
  1026. X
  1027. X\Xi{|?|<pattern>|?|}
  1028. XThis is just like the |/|<pattern>|/| search, except that it matches
  1029. Xonly once between calls to the reset operator. If <pattern> is empty,
  1030. Xthe most recent pattern from a previous match or replacement is used.
  1031. X
  1032. X\Xi{[|\$|<var> |=~|] \kwd{s}|/|<pattern>|/|<replacement>|/|[\kwd{g}][\kwd{i}][\kwd{e}][\kwd{o}]}
  1033. XSearches a string for a pattern, and if found, replaces that pattern
  1034. Xwith the replacement text and returns the number of substitutions
  1035. Xmade. Otherwise it returns false. 
  1036. X\\
  1037. XOptional modifiers: \kwd{g} replaces all occurrences of the pattern;
  1038. X\kwd{e} interprets the replacement string as an expression; \kwd{i}
  1039. Xand \kwd{o} as with |/|<pattern>|/| matching. Almost any delimiter may
  1040. Xreplace the slashes; if single quotes are used, no interpretation is
  1041. Xdone on the replacement string.
  1042. X\\
  1043. XIf bracketing quotes are used, <pattern> and <replacement> 
  1044. Xmay have their own delimiters, e.g. |s(foo)[bar]|.
  1045. X\\
  1046. XIf <pattern> is empty, the most recent pattern from a previous match or replacement is used.
  1047. X
  1048. X\Xi{\kwd{study}[\kwd{(}|\$|<var>\dag\kwd{)}*]}
  1049. XStudy the contents of |$|<var> in anticipation of doing many pattern
  1050. Xmatches on the contents before it is next modified.
  1051. X
  1052. X\Xi{[|\$|<var> |=~|] \kwd{tr}|/|<searchlist>|/|<replacementlist>|/|[\kwd{c}][\kwd{d}][\kwd{s}]}
  1053. XTranslates all occurrences of the characters found in the search list
  1054. Xwith the corresponding character in the replacement list. It returns
  1055. Xthe number of characters replaced. \kwd{y} may be used instead of \kwd{tr}. 
  1056. X\\
  1057. XOptional modifiers: \kwd{c} complements the <searchlist>; \kwd{d}
  1058. Xdeletes all characters not found in <searchlist>; \kwd{s} squeezes all
  1059. Xsequences of characters that are translated into the same target
  1060. Xcharacter into one occurrence of this character.
  1061. X
  1062. X\end{enum}
  1063. X
  1064. X\makeupspace{1cm}
  1065. X
  1066. X\section{System interaction} 
  1067. X
  1068. X\begin{enum}{1cm}
  1069. X
  1070. X\Xi{\kwd{alarm(}<expr>\kwd{)}*}
  1071. XSchedules a |SIGALRM| to be delivered after <expr> seconds. 
  1072. X
  1073. X\Xi{\kwd{chdir} [\kwd{(}<expr>\kwd{)}*]}
  1074. XChanges the working directory, |$ENV{"HOME"}| if <expr> is omitted.
  1075. X
  1076. X\Xi{\kwd{chroot(}<filename>\dag\kwd{)}*}
  1077. XChanges the root directory for the process and its children.
  1078. X
  1079. X\Xi{\kwd{die}[\kwd{(}<list>\kwd{)}*]}
  1080. XPrints the value of <list> to |STDERR| and exits with the current
  1081. Xvalue of |$!| (errno). If |$!| is 0, exits with the value of |($? >> 8)|.
  1082. XIf |($? >> 8)| is 0, exits with 255. <list> defaults to
  1083. X|"Died."|.
  1084. X
  1085. X\Xi{\kwd{exec(}<list>\kwd{)}*}
  1086. XExecutes the system command in <list>; does not return.
  1087. X
  1088. X\Xi{\kwd{exit(}<expr>\kwd{)}*}
  1089. XExits immediately with the value of |EXPR|.
  1090. X
  1091. X\Xi{\kwd{fork}}
  1092. XDoes a {\it fork\/}(2) system call. Returns the child pid to the parent
  1093. Xprocess and zero to the child process. 
  1094. X
  1095. X\Xi{\kwd{getlogin}}
  1096. XReturns the current login name as known by the system.
  1097. X
  1098. X\Xi{\kwd{getpgrp}[\kwd{(}<pid>\kwd{)}*]}
  1099. XReturns the process group for process <pid> (0, or omitted,  means the
  1100. Xcurrent process). 
  1101. X
  1102. X\Xi{\kwd{getppid}}
  1103. XReturns the process id of the parent process.
  1104. X
  1105. X\Xi{\kwd{getpriority(}<which>\kwd{,}<who>\kwd{)}}
  1106. XReturns the current priority for a process, process group, or user.
  1107. X
  1108. X\Xi{\kwd{kill(}<list>\kwd{)}*}
  1109. XSends a signal to a list of processes. The first element of the list
  1110. Xmust be the signal to send (numeric, or its name as a string). 
  1111. X
  1112. X\Xi{\kwd{setpgrp(}<pid>\kwd{,}<pgrp>\kwd{)}}
  1113. XSets the process group for the <pid> (0 = current process).
  1114. X
  1115. X\Xi{\kwd{setpriority(}<which>\kwd{,}<who>\kwd{,}<prio>\kwd{)}}
  1116. XSets the current priority for a process, process group, or a user.
  1117. X
  1118. X\Xi{\kwd{sleep}[\kwd{(}<expr>\kwd{)}*]}
  1119. XCauses the script to sleep for <expr> seconds, or forever if no
  1120. X<expr>. Returns the number of seconds actually slept. 
  1121. X
  1122. X\Xi{\kwd{syscall(}<list>\kwd{)}*}
  1123. XCalls the system call specified in the first element of the list,
  1124. Xpassing the rest of the list as arguments to the call. 
  1125. X
  1126. X\Xi{\kwd{system(}<list>\kwd{)}*}
  1127. XDoes exactly the same thing as \kwd{exec }<list> except that a fork is
  1128. Xdone first, and the parent process waits for the child process to complete. 
  1129. X
  1130. X\Xi{\kwd{times}}
  1131. XReturns a 4-element array (\$user, \$system, \$cuser, \$csystem) giving
  1132. Xthe user and system times, in seconds, for this process and the
  1133. Xchildren of this process.  
  1134. X
  1135. X\Xi{\kwd{umask}[\kwd{(}<expr>\kwd{)}*]}
  1136. XSets the umask for the process and returns the old one. If <expr> is
  1137. Xomitted, returns current umask value. 
  1138. X
  1139. X\Xi{\kwd{wait}}
  1140. XWaits for a child process to terminate and returns the pid of the
  1141. Xdeceased process (-1 if none). The status is returned in |$?|. 
  1142. X
  1143. X\Xi{\kwd{waitpid(}<pid>\kwd{,}<flags>\kwd{)}}
  1144. XPerforms the same function as the corresponding system call.
  1145. X
  1146. X\Xi{\kwd{warn(}<list>\kwd{)}*}
  1147. XPrints the message on |STDERR| like \kwd{die}, but doesn't exit.
  1148. X
  1149. X\end{enum}
  1150. X
  1151. X\makeuppage
  1152. X
  1153. X\section{Networking} 
  1154. X
  1155. X\begin{enum}{1cm}
  1156. X
  1157. X\Xi{\kwd{accept(}<newsocket>\kwd{,}<genericsocket>\kwd{)}}
  1158. XAccepts a new socket.
  1159. X
  1160. X\Xi{\kwd{bind(}<socket>\kwd{,}<name>\kwd{)}}
  1161. XBinds the <name> to the <socket>.
  1162. X
  1163. X\Xi{\kwd{connect(}<socket>\kwd{,}<name>\kwd{)}}
  1164. XConnects the <name> to the <socket>.
  1165. X
  1166. X\Xi{\kwd{getpeername(}<socket>\kwd{)}}
  1167. XReturns the socket address of the other end of the <socket>.
  1168. X
  1169. X\Xi{\kwd{getsockname(}<socket>\kwd{)}}
  1170. XReturns the name of the socket.
  1171. X
  1172. X\Xi{\kwd{getsockopt(}<socket>\kwd{,}<level>\kwd{,}<optname>\kwd{)}}
  1173. XReturns the socket options.
  1174. X
  1175. X\Xi{\kwd{listen(}<socket>\kwd{,}<queuesize>\kwd{)}}
  1176. XStarts listening on the specified <socket>.
  1177. X
  1178. X\Xi{\kwd{recv(}<socket>\kwd{,}<scalar>\kwd{,}<length>\kwd{,}<flags>\kwd{)}}
  1179. XReceives a message on <socket>.
  1180. X
  1181. X\Xi{\kwd{send(}<socket>\kwd{,}<msg>\kwd{,}<FLAGS[>\kwd{,}<to>]\kwd{)}}
  1182. XSends a message on the <socket>.
  1183. X
  1184. X\Xi{\kwd{setsockopt(}<socket>\kwd{,}<level>\kwd{,}<optname>\kwd{,}<optval>\kwd{)}}
  1185. XSets the requested socket option.
  1186. X
  1187. X\Xi{\kwd{shutdown(}<socket>\kwd{,}<how>\kwd{)}}
  1188. XShuts down a <socket>.
  1189. X
  1190. X\Xi{\kwd{socket(}<socket>\kwd{,}<domain>\kwd{,}<type>\kwd{,}<protocol>\kwd{)}}
  1191. XCreates a <socket> in <domain> with <type> and <protocol>.
  1192. X
  1193. X\Xi{\kwd{socketpair(}<socket1>\kwd{,}<socket2>\kwd{,}<domain>\kwd{,}<type>\kwd{,}<protocol>\kwd{)}}
  1194. XAs socket, but creates a pair of bi-directional sockets.
  1195. X
  1196. X\end{enum}
  1197. X
  1198. X\makeupspace{1cm}
  1199. X
  1200. X\section{SystemV IPC} 
  1201. X
  1202. XThe following functions all perform the same action as the
  1203. Xcorresponding system calls.
  1204. X
  1205. X\kwd{msgctl(}<id>\kwd{,}<cmd>\kwd{,}<args>\kwd{)} \\
  1206. X\kwd{msgget(}<key>\kwd{,}<flags>\kwd{)} \\
  1207. X\kwd{msgsnd(}<id>\kwd{,}<msg>\kwd{,}<flags>\kwd{)} \\
  1208. X\kwd{msgrcv(}<id>\kwd{,}\$<var>\kwd{,}<size>\kwd{,}<type>\kwd{,}<flags>\kwd{)} \\
  1209. X\kwd{semctl(}<id>\kwd{,}<semnum>\kwd{,}<cmd>\kwd{,}<arg>\kwd{)} \\
  1210. X\kwd{semget(}<key>\kwd{,}<nsems>\kwd{,}<size>\kwd{,}<flags>\kwd{)} \\
  1211. X\kwd{semop(}<key>\kwd{,}...\kwd{)} \\
  1212. X\kwd{shmctl(}<id>\kwd{,}<cmd>\kwd{,}<arg>\kwd{)} \\
  1213. X\kwd{shmget(}<key>\kwd{,}<size>\kwd{,}<flags>\kwd{)} \\
  1214. X\kwd{shmread(}<id>\kwd{,}\$<var>\kwd{,}<pos>\kwd{,}<size>\kwd{)} \\
  1215. X\kwd{shmwrite(}<id>\kwd{,}<string>\kwd{,}<pos>\kwd{,}<size>\kwd{)}
  1216. X
  1217. X\makeuppage
  1218. X
  1219. X\section{Miscellaneous} 
  1220. X
  1221. X\begin{enum}{1cm}
  1222. X
  1223. X\Xi{\kwd{caller}[\kwd{(}<expr>\kwd{)}]}
  1224. XReturns an array (\$package,\$file,\$line,...) for a specific subroutine
  1225. Xcall. ``|caller|'' returns this info for the current subroutine,
  1226. X``|caller(1)|'' for the caller of this subroutine etc..  
  1227. X
  1228. X\Xi{\kwd{defined(}<expr>\kwd{)}*}
  1229. XTests whether the lvalue <expr> has a real value.
  1230. X
  1231. X\Xi{\kwd{dump} [<label>]}
  1232. XImmediate core dump. When reincarnated, starts at <label>.
  1233. X
  1234. X\Xi{\kwd{local(}<list>\kwd{)}}
  1235. XCreates a scope for the listed variables local to the enclosing block,
  1236. Xsubroutine or eval. 
  1237. X
  1238. X\Xi{\kwd{package} <name>}
  1239. XDesignates the remainder of the current block as a package.
  1240. X
  1241. X\Xi{\kwd{require(}\oEXPR\kwd{)}*}
  1242. XIncludes the specified file from the perl library. Does not include
  1243. Xmore than once, and yields a fatal error if the file does not include OK. 
  1244. X
  1245. X\Xi{\kwd{reset} [\kwd{(}<expr>\kwd{)}*]}
  1246. XResets |??| searches so that they work again. <expr> is a list of
  1247. Xsingle letters. All variables and arrays beginning with one of those
  1248. Xletters are reset to their pristine state.  Only affects the current
  1249. Xpackage.
  1250. X
  1251. X\Xi{\kwd{scalar(}<expr>\kwd{)}}
  1252. XForces evaluation of <expr> in scalar context.
  1253. X
  1254. X\Xi{\kwd{sub} <name> \{ <expr> |;| ... \}}
  1255. XDesignates <name> as a subroutine. Parameters are passed by reference
  1256. Xas array |@_|. Returns the value of the last expression evaluated. 
  1257. X
  1258. X\Xi{\kwd{undef}[\kwd{(}<lvalue>\kwd{)}*]}
  1259. XUndefines the <lvalue>. Always returns the undefined value.
  1260. X
  1261. X\Xi{\kwd{wantarray}}
  1262. XReturns true if the current context expects an array value.
  1263. X
  1264. X\end{enum}
  1265. X
  1266. X
  1267. X\section{Formats} 
  1268. X
  1269. X\kwd{format} [<name>] |=| \\
  1270. X<formlist> \\
  1271. X|.|
  1272. X
  1273. X<formlist> pictures the lines, and contains the arguments which will
  1274. Xgive values to the fields in the lines. Picture fields are:
  1275. X
  1276. X|  @<<<...  | left adjusted field, repeat the |<| to denote the desired
  1277. Xwidth; \\
  1278. X|  @>>>...  | right adjusted field; \\
  1279. X|  @|\|\|\||...  | centered field; \\
  1280. X|  @#.##... | numeric format with implied decimal point; \\
  1281. X|  @*       | a multi-line field.
  1282. X
  1283. XUse \^ instead of |@| for multi-line block filling.
  1284. X
  1285. XUse |~| at the beginning of a line to suppress unwanted empty lines.
  1286. X
  1287. XUse |~~| at the beginning of a line to have this format line repeated
  1288. Xuntil all fields are exhausted. 
  1289. X
  1290. XUse |$-| to zero to force a page break.
  1291. X
  1292. XSee also |$|\^, |$~|, |$-| and |$=| in section ``Special Variables''.
  1293. X
  1294. X
  1295. X\section{Info from system files} 
  1296. XSee the manual about return values in scalar context.
  1297. X
  1298. X{\large\sl passwd} \\
  1299. XReturns (\$name, \$passwd, \$uid, \$gid, \$quota, \$comment, \$gcos, \$dir, \$shell).
  1300. X
  1301. X\begin{enum}{6cm}
  1302. X
  1303. X\Xi{\kwd{endpwent}}    Ends lookup processing.
  1304. X
  1305. X\Xi{\kwd{getpwent}}    Gets next info.
  1306. X
  1307. X\Xi{\kwd{getpwnam(}<name>\kwd{)}}    Gets info by name. 
  1308. X
  1309. X\Xi{\kwd{getpwuid(}<uid>\kwd{)}}    Gets info by uid.
  1310. X
  1311. X\Xi{\kwd{setpwent}}    Resets lookup processing.
  1312. X
  1313. X\end{enum}
  1314. X
  1315. X{\vskip6pt\large\sl group} \\
  1316. XReturns (\$name, \$passwd, \$gid, \$members).
  1317. X
  1318. X\begin{enum}{6cm}
  1319. X
  1320. X\Xi{\kwd{endgrent}}    Ends lookup processing.
  1321. X
  1322. X\Xi{\kwd{getgrgid(}<gid>\kwd{)}}    Gets info by group id. 
  1323. X
  1324. X\Xi{\kwd{getgrnam(}<name>\kwd{)}}    Gets info by name.
  1325. X
  1326. X\Xi{\kwd{getgrent}}    Gets next info.
  1327. X
  1328. X\Xi{\kwd{setgrent}}    Resets lookup processing.
  1329. X
  1330. X\end{enum}
  1331. X
  1332. X{\vskip6pt\large\sl hosts} \\
  1333. XReturns (\$name, \$aliases, \$addrtype, \$length, @addrs).
  1334. X
  1335. X\begin{enum}{6cm}
  1336. X
  1337. X\Xi{\kwd{endhostent}}    Ends lookup processing.
  1338. X
  1339. X\Xi{\kwd{gethostbyaddr(}<addr>\kwd{,}<addrtype>\kwd{)}}    Gets info by address.
  1340. X
  1341. X\Xi{\kwd{gethostbyname(}<name>\kwd{)}}    Gets info by name.
  1342. X
  1343. X\Xi{\kwd{gethostent}}    Gets next info.
  1344. X
  1345. X\Xi{\kwd{sethostent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1346. X
  1347. X\end{enum}
  1348. X
  1349. X{\vskip6pt\large\sl networks} \\
  1350. XReturns (\$name, \$aliases, \$addrtype, \$net).
  1351. X
  1352. X\begin{enum}{6cm}
  1353. X
  1354. X\Xi{\kwd{endnetent}}    Ends lookup processing.
  1355. X
  1356. X\Xi{\kwd{getnetbyaddr(}<addr>\kwd{,}<type>\kwd{)}}    Gets info by address and type.
  1357. X
  1358. X\Xi{\kwd{getnetbyname(}<name>\kwd{)}}    Gets info by name.
  1359. X
  1360. X\Xi{\kwd{getnetent}}    Gets next info.
  1361. X
  1362. X\Xi{\kwd{setnetent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1363. X
  1364. X\end{enum}
  1365. X
  1366. X{\vskip6pt\large\sl services} \\
  1367. XReturns (\$name, \$aliases, \$port, \$proto).
  1368. X
  1369. X\begin{enum}{6cm}
  1370. X
  1371. X\Xi{\kwd{endservent}}    Ends lookup processing.
  1372. X
  1373. X\Xi{\kwd{getservbyname(}<name>\kwd{, }<proto>\kwd{)}}    Gets info by name. 
  1374. X
  1375. X\Xi{\kwd{getservbyport(}<port>\kwd{, }<proto>\kwd{)}}    Gets info by port.
  1376. X
  1377. X\Xi{\kwd{getservent}}    Gets next info.
  1378. X
  1379. X\Xi{\kwd{setservent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1380. X
  1381. X\end{enum}
  1382. X
  1383. X{\vskip6pt\large\sl protocols} \\
  1384. X
  1385. XReturns (\$name, \$aliases, \$proto).
  1386. X
  1387. X\begin{enum}{6cm}
  1388. X
  1389. X\Xi{\kwd{endprotoent}}    Ends lookup processing.
  1390. X
  1391. X\Xi{\kwd{getprotobyname(}<name>\kwd{)}}    Gets info by name.
  1392. X
  1393. X\Xi{\kwd{getprotobynumber(}<number>\kwd{)}}    Gets info by number.
  1394. X
  1395. X\Xi{\kwd{getprotoent}}    Gets next info.
  1396. X
  1397. X\Xi{\kwd{setprotoent(}<stayopen>\kwd{)}}    Resets lookup processing.
  1398. X
  1399. X\end{enum}
  1400. X
  1401. X
  1402. X\section{Regular expressions} 
  1403. X
  1404. XEach character matches itself, unless it is one of the special
  1405. Xcharacters |+?.*()[]{}|\||\|.
  1406. X
  1407. X\begin{enum}{1cm}
  1408. X
  1409. X\Xj{|.|}
  1410. Xmatches an arbitrary character, but not a newline.
  1411. X
  1412. X\Xj{|(|\ldots|)|}
  1413. Xgroups a series of pattern elements to a single element.
  1414. X
  1415. X\Xj{|+|}
  1416. Xmatches the preceding pattern element one or more times.
  1417. X
  1418. X\Xj{|?|}
  1419. Xmatches zero or one times.
  1420. X
  1421. X\Xj{|*|}
  1422. Xmatches zero or more times.
  1423. X
  1424. X\Xj{\{<n>|,|<m>\}}
  1425. Xdenotes the minimum <n> and maximum <m> match count. |{|<n>|}| means
  1426. Xexactly <n> times; |{|<n>|,}| means at least <n> times. 
  1427. X
  1428. X\Xj{|\char`\[|\ldots|\char`\]|}
  1429. Xdenotes a class of characters to match. |[|\^\ldots|]| negates the class.
  1430. X
  1431. X\Xj{|(|\ldots\|\ldots\|\ldots|)|}
  1432. Xmatches one of the alternatives.
  1433. X
  1434. X\end{enum}
  1435. X
  1436. XNon-alphanumerics can be escaped from their special meaning using a
  1437. X|\|.
  1438. X
  1439. X\begin{enum}{1cm}
  1440. X
  1441. X\Xj{|\char`\\w|}
  1442. Xmatches alphanumeric, including ``|_|'', |\W| matches non-alphanumeric.
  1443. X
  1444. X\Xj{|\char`\\b|}
  1445. Xmatches word boundaries, |\B| matches non-boundaries.
  1446. X
  1447. X\Xj{|\char`\\s|}
  1448. Xmatches whitespace, |\S| matches non-whitespace.
  1449. X
  1450. X\Xj{|\char`\\d|}
  1451. Xmatches numeric, |\D| matches non-numeric.
  1452. X
  1453. X\Xj{|\char`\\n|, |\char`\\r|, |\char`\\f|, |\char`\\t| etc.} 
  1454. Xhave their usual meaning.
  1455. X
  1456. X\Xj{|\char`\\w|, |\char`\\s| and |\char`\\d|}
  1457. X may be used within character classes, |\b| denotes backspace in this context.
  1458. X
  1459. X\Xj{|\char`\\1|\ldots|\char`\\9|}
  1460. Xrefer to matched sub-expressions, grouped with |()|, inside
  1461. Xthe match. 
  1462. X
  1463. X\Xj{|\char`\\10|}
  1464. Xand up can also be used if the pattern
  1465. Xmatches that many sub-expressions. 
  1466. X
  1467. X\end{enum}
  1468. X
  1469. XSee also |$1|\ldots|$9|, |$+|, |$&|, |$`| and |$'| in section ``Special
  1470. XVariables''.
  1471. X
  1472. X
  1473. X
  1474. X\section{Special variables} 
  1475. X
  1476. XThe following variables are global and should be localized in subroutines:
  1477. X
  1478. X\begin{enum}{1cm}
  1479. X
  1480. X\Xi{|\char`\$\char`\_|}
  1481. XThe default input and pattern-searching space.
  1482. X
  1483. X\Xi{|\char`\$\char`\.|}
  1484. XThe current input line number of the last filehandle that was read.
  1485. X
  1486. X\Xi{|\char`\$\char`\/|}
  1487. XThe input record separator, newline by default. May be multi-character.
  1488. X
  1489. X\Xi{|\char`\$\char`\,|}
  1490. XThe output field separator for the print operator.
  1491. X
  1492. X\Xi{|\char`\$\char`\"|}
  1493. XThe separator which joins elements of arrays interpolated in strings.
  1494. X
  1495. X\Xi{|\char`\$\char`\\|}
  1496. XThe output record separator for the print operator.
  1497. X
  1498. X\Xi{|\char`\$\char`\#|}
  1499. XThe output format for printed numbers. Initial value is ``|%.20g|''.
  1500. X
  1501. X\Xi{|\char`\$\char`\*|}
  1502. XSet to 1 to do multiline matching within a string, 0 to assume strings
  1503. Xcontain a single line. Default is 0. 
  1504. X
  1505. X\Xi{|\char`\$\char`\?|}
  1506. XThe status returned by the last |`|<command>|`|, pipe close or
  1507. X\kwd{system} operator. 
  1508. X
  1509. X\Xi{|\char`\$\char`\]|}
  1510. XThe perl version string (as displayed with |perl -v|), or version number.
  1511. X
  1512. X\Xi{|\char`\$\char`\[|}
  1513. XThe index of the first element in an array, and of the first character
  1514. Xin a substring. Default is 0. 
  1515. X
  1516. X\Xi{|\char`\$\char`\;|}
  1517. XThe subscript separator for multi-dimensional array emulation. Default
  1518. Xis |"\034"|. 
  1519. X
  1520. X\Xi{|\char`\$\char`\!|}
  1521. XIf used in a numeric context, yields the current value of errno. If
  1522. Xused in a string context, yields the corresponding error string. 
  1523. X
  1524. X\Xi{|\char`\$\char`\@|}
  1525. XThe perl error message from the last eval or \kwd{do} <expr> command.
  1526. X
  1527. X\Xi{|\char`\$\char`\:|}
  1528. XThe set of characters after which a string may be broken to fill
  1529. Xcontinuation fields (starting with ``|^|'') in a format. 
  1530. X
  1531. X\Xi{|\char`\$\char`\0|}
  1532. XThe name of the file containing the perl script being executed. May be
  1533. Xassigned to. 
  1534. X
  1535. X\Xi{|\char`\$\char`\$|}
  1536. XThe process number of the perl running this script. Altered (in the
  1537. Xchild process) by \kwd{fork}. 
  1538. X
  1539. X\Xi{|\char`\$\char`\<|}
  1540. XThe real uid of this process.
  1541. X
  1542. X\Xi{|\char`\$\char`\>|}
  1543. XThe effective uid of this process. 
  1544. X
  1545. X\Xi{|\char`\$\char`\(|}
  1546. XThe real gid of this process.
  1547. X
  1548. X\Xi{|\char`\$\char`\)|}
  1549. XThe effective gid of this process.
  1550. X
  1551. X\Xi{|\char`\$\char`\^D|}
  1552. XThe debug flags as passed to perl using |-D| .
  1553. X
  1554. X\Xi{|\char`\$\char`\^F|}
  1555. XThe highest system file descriptor, ordinarily 2.
  1556. X
  1557. X\Xi{|\char`\${\char`\^}I|}
  1558. XIn-place edit extension as passed to perl using |-i| .
  1559. X
  1560. X\Xi{|\char`\$\char`\^L|}
  1561. XFormfeed character used in formats.
  1562. X
  1563. X\Xi{|\char`\$\char`\^P|}
  1564. XInternal debugging flag.
  1565. X
  1566. X\Xi{|\char`\$\char`\^T|}
  1567. XThe time (as delivered by \kwd{time}) when the program started. This
  1568. Xvalue is used by the file test operators ``|-M|'', ``|-A|'' and
  1569. X``|-C|''.
  1570. X
  1571. X\Xi{|\char`\$\char`\^W|}
  1572. XThe value if the |-w| option as passed to perl.
  1573. X
  1574. X\Xi{|\char`\$\char`\^X|}
  1575. XThe name by which this perl was invoked.
  1576. X
  1577. X\end{enum}
  1578. X
  1579. XThe following variables are context dependent and need not be
  1580. Xlocalized:
  1581. X
  1582. X\begin{enum}{1cm}
  1583. X
  1584. X\Xi{|\char`\$\char`\%|}
  1585. XThe current page number of the currently selected output channel.
  1586. X
  1587. X\Xi{|\char`\$\char`\=|}
  1588. XThe page length of the current output channel. Default is 60 lines.
  1589. X
  1590. X\Xi{|\char`\$\char`\-|}
  1591. XThe number of lines left on the page.
  1592. X
  1593. X\Xi{|\char`\$\char`\~|}
  1594. XThe name of the current report format.
  1595. X
  1596. X\Xi{|\char`\$\char`\^|}
  1597. XThe name of the current top-of-page format.
  1598. X
  1599. X\Xi{|\char`\$\char`\||}
  1600. XIf set to nonzero, forces a flush after every write or print on the
  1601. Xcurrently selected output channel. Default is 0. 
  1602. X
  1603. X\Xj{|\char`\$ARGV|}
  1604. XThe name of the current file when reading from |<>| .
  1605. X\end{enum}
  1606. X
  1607. XThe following variables are always local to the current block:
  1608. X
  1609. X\begin{enum}{1cm}
  1610. X
  1611. X\Xi{|\char`\$\char`\&|}
  1612. XThe string matched by the last successful pattern match.
  1613. X
  1614. X\Xi{|\char`\$\char`\`|}
  1615. XThe string preceding what was matched by the last successful match.
  1616. X
  1617. X\Xi{|\char`\$\char`\'|}
  1618. XThe string following what was matched by the last successful match. 
  1619. X
  1620. X\Xi{|\char`\$\char`\+|}
  1621. XThe last bracket matched by the last search pattern.
  1622. X
  1623. X\Xi{\$|1|\ldots\$|9|\ldots}
  1624. XContains the subpattern from the corresponding set of parentheses in
  1625. Xthe last pattern successfully matched.
  1626. X|$10|\ldots and up are only available if the
  1627. Xmatch contained that many sub-expressions. 
  1628. X
  1629. X\end{enum}
  1630. X
  1631. X
  1632. X
  1633. X
  1634. X\section{Special arrays} 
  1635. X
  1636. X\begin{enum}{1.5cm}
  1637. X
  1638. X\Xi{|@ARGV|}
  1639. XContains the command line arguments for the script (not including the command name).
  1640. X
  1641. X\Xi{|@INC|}
  1642. XContains the list of places to look for perl scripts to be evaluated
  1643. Xby the \kwd{do} <filename> and \kwd{require} commands. 
  1644. X
  1645. X\Xi{|@\char`\_|}
  1646. XParameter array for subroutines. Also used by \kwd{split} if not in
  1647. Xarray context. 
  1648. X
  1649. X\Xi{|\char`\%ENV|}
  1650. XContains the current environment.
  1651. X
  1652. X\Xi{|\char`\%INC|}
  1653. XList of files that have been \kwd{require}d or \kwd{do}ne.
  1654. X
  1655. X\Xi{|\char`\%SIG|}Used to set signal handlers for various signals.
  1656. X
  1657. X\end{enum}
  1658. X
  1659. X
  1660. X\section{The perl debugger} 
  1661. X
  1662. XThe perl symbolic debugger is invoked with |perl -d|.
  1663. X
  1664. X\begin{enum}{2.5cm}
  1665. X
  1666. X\Xi{|h|}
  1667. XPrints out a help message.
  1668. X
  1669. X\Xi{|T|}
  1670. XStack trace.
  1671. X
  1672. X\Xi{|s|}
  1673. XSingle steps.
  1674. X
  1675. X\Xi{|n|}
  1676. XSingle steps around subroutine call.
  1677. X
  1678. X\Xi{|r|}
  1679. XReturns from the current subroutine.
  1680. X
  1681. X\Xi{|c| [<line>]}
  1682. XContinues (until <line>, or another breakpoint or exit).
  1683. X
  1684. X\Xi{\fbox{<ret>}}
  1685. XRepeats last |s| or |n|.
  1686. X
  1687. X\Xi{|l| [<range>]}
  1688. XLists a range of lines. <range> may be a number, start-end,
  1689. Xstart+amount, or a subroutine name. If omitted, lists next window. 
  1690. X
  1691. X\Xi{|f| <file>}
  1692. XSwitches to <file> and start listing it.
  1693. X
  1694. X\Xi{|-|}
  1695. XLists previous window.
  1696. X
  1697. X\Xi{|w|}
  1698. XLists window around current line.
  1699. X
  1700. X\Xi{|l| <sub>}
  1701. XLists the named <sub>routine.
  1702. X
  1703. X\Xi{|/|<pattern>|/|}
  1704. XForward search for <pattern>.
  1705. X
  1706. X\Xi{|?|<pattern>|?|}
  1707. XBackward search for <pattern>.
  1708. X
  1709. X\Xi{|L|}
  1710. XLists lines that have breakpoints or actions.
  1711. X
  1712. X\Xi{|S|}
  1713. XList the names of all subroutines.
  1714. X
  1715. X\Xi{|t|}
  1716. XToggles trace mode.
  1717. X
  1718. X\Xi{|b| [<line> [<condition>]]}
  1719. XSets breakpoint at <line>, default: current line.
  1720. X
  1721. X\Xi{|b| <subname> [<condition>]}
  1722. XSets breakpoint at the subroutine.
  1723. X
  1724. X\Xi{|S|}
  1725. XLists names of all subroutines.
  1726. X
  1727. X\Xi{|d| [<line>]}
  1728. XDeletes breakpoint at the given line.
  1729. X
  1730. X\Xi{|D|}
  1731. XDeletes all breakpoints.
  1732. X
  1733. X\Xi{|a| <line command>}
  1734. XSets an action for line.
  1735. X
  1736. X\Xi{|A|}
  1737. XDeletes all line actions.
  1738. X
  1739. X\Xi{|\char`\<| <command>}
  1740. XSets an action to be executed before every debugger prompt.
  1741. X
  1742. X\Xi{|\char`\>| <command>}
  1743. XSets an action to be executed before every |s|, |c| or |n| command.
  1744. X
  1745. X\Xi{|V| [<package> [<vars>] ]}
  1746. XLists all variables in a package. Default package is main.
  1747. X
  1748. X\Xi{|X| [<vars>]}
  1749. XLike |V|, but assumes current package.
  1750. X
  1751. X\Xi{|!| [ [-]<number>]}
  1752. XRedo a debugging command. Default is previous command.
  1753. X
  1754. X\Xi{|H| [-<number>]}
  1755. XDisplays the last -<number> commands of more than one letter.
  1756. X
  1757. X\Xi{|q|}
  1758. XQuits. You may also use your \fbox{<eof>} character.
  1759. X
  1760. X\Xi{<command>}
  1761. XExecutes <command> as a perl statement.
  1762. X
  1763. X\Xi{|p| \oEXPR}
  1764. XPrints <expr>.
  1765. X
  1766. X\Xi{|=|< >[<alias value>]}
  1767. XSets alias, or lists current aliases.
  1768. X
  1769. X\end{enum}
  1770. X
  1771. X\makeuppage
  1772. X
  1773. X\section{Environment variables} 
  1774. X
  1775. XPerl uses the following environment variables.
  1776. X
  1777. X\begin{enum}{1.5cm}
  1778. X
  1779. X\Xi{|HOME|}
  1780. XUsed if \kwd{chdir} has no argument.
  1781. X
  1782. X\Xi{|LOGDIR|}
  1783. XUsed if \kwd{chdir} has no argument and |HOME| is not set.
  1784. X
  1785. X\Xi{|PATH|}
  1786. XUsed in executing subprocesses, and in finding the perl script if |-S|
  1787. Xis used.
  1788. X
  1789. X\Xi{|PERLLIB|}
  1790. XA colon-separated list of directories to look for perl library files
  1791. Xbefore looking in the standard library and the current directory.
  1792. X
  1793. X\Xi{|PERLDB|}
  1794. XThe command to get the debugger code. Defaults to 
  1795. X\hbox{|require 'perldb.pl'|}. 
  1796. X
  1797. X\end{enum}
  1798. X
  1799. X\makeupspace{1cm}
  1800. X
  1801. X\unnumbered{Notes}
  1802. X\vfill
  1803. X\makebox[\textwidth]{Perl Reference Guide Revision \refrev \hfill
  1804. X\copyright 1989,1992 Johan Vromans}
  1805. X
  1806. X
  1807. X\end{document}
  1808. END_OF_FILE
  1809.   if test 48498 -ne `wc -c <'refbase.tex'`; then
  1810.     echo shar: \"'refbase.tex'\" unpacked with wrong size!
  1811.   fi
  1812.   # end of 'refbase.tex'
  1813. fi
  1814. echo shar: End of archive 2 \(of 4\).
  1815. cp /dev/null ark2isdone
  1816. MISSING=""
  1817. for I in 1 2 3 4 ; do
  1818.     if test ! -f ark${I}isdone ; then
  1819.     MISSING="${MISSING} ${I}"
  1820.     fi
  1821. done
  1822. if test "${MISSING}" = "" ; then
  1823.     echo You have unpacked all 4 archives.
  1824.     rm -f ark[1-9]isdone
  1825. else
  1826.     echo You still must unpack the following archives:
  1827.     echo "        " ${MISSING}
  1828. fi
  1829. exit 0
  1830. exit 0 # Just in case...
  1831.